Tootsville::Infinity-Prompt-Reply

Function

Infinity-Prompt-Reply names a function, with lambda list (D USER RECIPIENT/S):

Accept a reply to a server-initiated prompt

Lisp PROMPT-REPLY = JSON promptReply

Usage

{ id: ID, reply: TOKEN }

Overview of Prompts

Server initiates prompt with:

 { "from" : "prompt",
   "id" : $ID,
   "label" : $LABEL,
   "label_en_US" : $LABEL,
   "title" : $TITLE,
   [ "attachUser" : $AVATAR_LABEL || "attachItem" : $ITEM_ID ] ,
   "msg" : $TEXT,
   "replies":
     { $TOKEN :
       { "label" : $BUTTON_LABEL,
         "label_en_US" : $BUTTON_LABEL,
         "type" : $BUTTON_TYPE },
       [ … ]
     }
 }

Where:

$ID

arbitrary string with no 0 (null byte) representing this question uniquely. This is not an user-visible string.

$LABEL

concatenated to the window title, but can be used to special-case / theme dialogs in future for certain purposes

$TITLE

dialog title

Only one of either “attachUser'' or ``attachItem” will be included. $AVATAR_LABEL is the full avatar label of the user/avatar to which the prompt should be attached — including “$” and instance ID, if necessary — where $ITEM_ID is the room variable item ID for a placed item in the room.

$TEXT = message text, may have n, will often need word-wrapping, and ideally might make use of scroll bars

The "replies" assoc-array is of arbitrary length, where the key to each item is a $TOKEN, again an arbitrary string without 0 to represent this response uniquely. This is not an user-visible string.

$BUTTON_LABEL = the text to display. In future, the client may want to special-case specific text to use icons or something: e.g. "OK" will always be sent as precisely "OK" in English locale.

$BUTTON_TYPE = the type of the button for theming purposes only. This is from the enumerated set [ "aff" | "neg" | "neu" ];

aff

affirmative button, e.g. green button

neg

negative button, e.g. red button

neu

neutral button, e.g. purple button

To simplify future i18n/l10n efforts, the $LABEL and $BUTTON_LABEL will always be sent twice. The user's current language version will be in the "label" properties. The versions of those strings in the "en_US" locale will always be in the "label_en_US" properties. For purposes of theming and such, the label_en_US properties should be considered; the "label" properties, however, should always be used in presentation to the end-user.

Example:

 { "from": "prompt",
   "status": "true",
   "id": "fountain/tootSquare/þ=?/x'deadbeef'",
   "label": "Fountain", 
   "label_en_US": "Fountain",
   "title": "Make a Wish?", 
   "msg": "Do you want to make a wish on the Toot Square fountain?",
   "replies":
   { "yes": { "label": "Make a Wish!", 
                "label_en_US": "Make a Wish!", 
                "type": "aff" },
     "no": { "label": "Not now", 
               "label_en_US": "Not now", 
               "type": "neg" }
   }
 }

The client's response is a bit simpler:

 { "c": "promptReply", "d": { "id": $ID, "reply": $TOKEN } }

e.g.

 { "c":"promptReply",
   "d": { "id":  "fountain/tootSquare/þ=?/x'deadbeef'", 
            "reply": "yes" } }

As a special-case, for the reply only, the special $TOKEN of "close" should be sent if the user dismissed the dialog box with the close button.

I'd suggest that the GUI attach anonymous functions with the reply packets already constructed to the various dialog box controls at creation time, rather than trying to manage some queue of pending prompts.

To handle user expectations, it would be best to display the button in a "down" state until receiving the server's acknowledgement of the "promptReply" and disallow multiple-clicking in the window.

The server will respond with

 { "from": "promptReply", "status": "true", "id": $ID }

For debugging purposes, the server may reply with

 { from: "promptReply", "status": false, err: $ERR }

Where $ERR will be a brief description of the problem.

reply.notFound

a reply button that was not a valid $TOKEN from the "prompt" command nor the special case close.

id.notFound

a reply to a prompt that was not (recently) asked.

A prompt ID is not valid across sessions; pending prompts should be auto-closed on logout. Prompts can, however, remain active indefinitely, even across room joins.

Canceling a prompt

Optional implementation: the server may cancel an outstanding prompt request by sending a packet with the following properties:

{ from: prompt
  status: true
  cancel: $ID }

Client applications may choose to dismiss the prompt automatically upon receiving such a packet. Failure to do so is not an error, however, later attempting to reply to a canceled prompt will return status: false, err: id.notFound. Clients must accept a cancelation packet silently if they do not process it.

File

Defined in file src/infinity/legacy-commands.lisp.